This document contains late corrections to the discussion of the in-limbo flag in the OpenDoc Programmer’s Guide for the Mac OS, principally in the section "Undo and Embedded Frames" on pages 265–266. Please ignore the discussion in that section, including table 6-4, and instead follow the instructions in this note.
Every frame has a private flag, the in-limbo flag, that identifies frames that are not in the document layout. A frame is only in limbo when it has been removed, logically, from the document content, but still referenced by the part in which it was embedded. For example, a frame that has been cut is in limbo until the cut is committed by disposing the undo action for the cut; at that time the frame is removed from the part it previously displayed. (Note: Cutting a frame does not necessarily cut the part it displays; the part may still be displayed via other frames.) Note that a frame that is not currently connected to a part is not in limbo as long as its still logically part of the document layout. In a typical document, there may be many frames that are not visible, have no facets, and have not been internalized, but are not in limbo.
Your editor is required to inspect or set the in-limbo flag of its embedded frames according to these instructions. The in-limbo flag allows two or more distinct parts that have performed operations involving an embedded frame, like drag and drop, to ensure that the frame is eventually removed from the part it displays if the final fate of the frame leaves it out of the document layout. If your editor does not support embedding, it doesn’t have to worry about in-limbo flags.
Whenever your part deletes, cuts, pastes, drags, or drops an embedded frame, you must keep a reference to that frame in an undo action. When you take that action, when you undo or redo that action, and when you commit that action in your DisposeActionState method, you must set the frame’s in-limbo flag according to the instructions here.
You set the value of a frame’s in-limbo flag by calling its SetInLimbo method, passing either kODTrue or kODFalse. You can determine the value of a frame’s in-limbo flag by calling its IsInLimbo method.
When a frame is initially created, whether through CreateFrame or by cloning, its in-limbo flag is cleared. (Note, however, that cloning doesn’t always create new frames; during a drag-move, for example, cloning can deliver an existing frame and in this case the in-limbo flag will be kODTrue, as discussed below.)
Handling the in-limbo flag boils down to three simple rules (the first rule is a little more complicated during drag and drop, and is explained after the basic rules):
(1) When your part removes an embedded frame from your content model, by deleting or cutting an embedded frame, set the in-limbo flag of the frame to kODTrue. If your part undoes the deletion or cut, set the in-limbo flag to kODFalse. If your part redoes the deletion or cut, set the in-limbo flag to kODTrue.
(2) When adding an embedded frame to your content model, whether by pasting or dropping a frame, or by creating a new frame, set the in-limbo flag to kODFalse. (This is not necessary if you just created the frame, but it doesn't hurt.) If your part undoes the embedding, set the in-limbo flag to kODTrue. If your part redoes the embedding, set the in-limbo flag to kODFalse.
(3) When a call to your part’s DisposeActionState method commits an action that, by itself, would remove an embedded frame from your content, call IsInLimbo. If IsInLimbo returns kODTrue, remove the frame (by calling ODFrame::Remove), if it returns kODFalse, just release it (by calling ODFrame::Release). If you remove a frame as part of a non-undoable action, such as updating a link, and did not set the in-limbo flag to kODTrue, you should not make this test, but just remove the frame.
Your editor must be a little smarter in implementing rule (1) when it initiates a drag. Your part won’t know until StartDrag returns whether the operation was a move or a copy, but when initiating any drag that could be a move, set the in-limbo flag of each dragged frame to kODTrue. If as a result of StartDrag you do not actually follow through by removing the frames from your content, restore each one by setting the in-limbo status to kODFalse. (In general, that's when StartDrag returns other than kODDropMove, but if the part optimizes within the part moves, this would apply in that situation as well). Never set the in-limbo flags to kODTrue after StartDrag returns, even if you remove the frames from your content, since the frames may now be embedded in another part.
When undoing and redoing a drag-move, calls to SetInLimbo should be made when the begin action is undone or redone, not when the end action is undone or redone. This will ensure that during an undo, the drag is undone after the drop, and that during a redo, the drop is redone after the drag.
In version 1.0 of OpenDoc, you must trap the error kODErrInvalidFrame thrown by IsInLimbo. If this error is trapped, treat this as a result of kODFalse, and do not reraise the error. This works around a bug in OpenDoc 1.0. It should not be necessary to trap this error in future releases.
